package com.srmt.feishu.client;

import com.lark.oapi.service.drive.v1.model.*;

/**
 * 云盘服务接口
 *
 * 定义了飞书云盘相关的所有操作
 *
 * <h3>重构说明（v6.0.0）：</h3>
 * <ul>
 *   <li>所有方法返回具体数据类型，不再返回Resp对象</li>
 *   <li>响应校验统一在服务层处理</li>
 *   <li>失败时统一抛出FeishuApiException</li>
 * </ul>
 *
 * @author SRMT Development Team
 * @since 1.0.0
 * @version 6.0.0 统一响应处理层重构
 */
public interface DriveService {

    /**
     * 复制文件
     *
     * @param req 复制文件请求
     * @return 新文件的token
     * @throws com.srmt.feishu.client.exception.FeishuApiException 如果API调用失败
     * @throws Exception 如果其他错误
     */
    String copyFile(CopyFileReq req) throws Exception;

    /**
     * 删除文件
     *
     * @param req 删除文件请求
     * @throws com.srmt.feishu.client.exception.FeishuApiException 如果API调用失败
     * @throws Exception 如果其他错误
     */
    void deleteFile(DeleteFileReq req) throws Exception;

    /**
     * 创建权限成员
     *
     * @param req 创建权限成员请求
     * @return 创建的权限成员对象
     * @throws com.srmt.feishu.client.exception.FeishuApiException 如果API调用失败
     * @throws Exception 如果其他错误
     */
    BaseMember createPermissionMember(CreatePermissionMemberReq req) throws Exception;

    /**
     * 更新权限成员
     *
     * @param req 更新权限成员请求
     * @return 更新后的权限成员对象
     * @throws com.srmt.feishu.client.exception.FeishuApiException 如果API调用失败
     * @throws Exception 如果其他错误
     */
    BaseMember updatePermissionMember(UpdatePermissionMemberReq req) throws Exception;

    /**
     * 删除权限成员
     *
     * @param req 删除权限成员请求
     * @throws com.srmt.feishu.client.exception.FeishuApiException 如果API调用失败
     * @throws Exception 如果其他错误
     */
    void deletePermissionMember(DeletePermissionMemberReq req) throws Exception;

    /**
     * 列出权限成员
     *
     * @param req 列出权限成员请求
     * @return 权限成员数组
     * @throws com.srmt.feishu.client.exception.FeishuApiException 如果API调用失败
     * @throws Exception 如果其他错误
     */
    Member[] listPermissionMember(ListPermissionMemberReq req) throws Exception;
}